home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Amiga Format CD 46
/
Amiga Format CD46 (1999-10-20)(Future Publishing)(GB)[!][issue 1999-12].iso
/
-serious-
/
programming
/
other
/
cop
/
cop.doc
< prev
next >
Wrap
Text File
|
1999-09-06
|
141KB
|
2,841 lines
$VER: COP Doc 1.20 (28.3.99) (c) THOR 28 Mar 1999
*****************************************************************************
** **
** ___________ **
** \ */ **
** /----------- ####### ####### ######## **
** | ^ | ## ## ## ## ## ## **
** | _\ ## ## ## ## ## Version 1.77 **
** | | ## ## ## ######## **
** | --| ## ## ## ## **
** +-----/ ## ## ## ## ## **
** | | ####### ####### ## (c) 1993-1999 THOR-Software **
** **
** **
** A Low Level Debugger for all Amiga Systems **
** **
*****************************************************************************
by
_______ _____ _____ __ _
/ / / / / / / \/_/ //_/_
/ /____/ / / /____/ ___ / ____// / _ __
/ / / / / / \ / /|/ / / / /_/ / /\_/_/
/ / / /____/ / / _/__/_/ /__/|_/_/_/ /_/_/ /_
/
+-----------------------------------------------------------------------+
| |
| This release of COP is full FREEWARE... |
| ...but possibly the next release won't. |
| |
| You are free to copy this program, as long as: |
| |
| - All files in this drawer are included. |
| - ALL COMERCIAL USE IS STRICTLY PERMITED : |
| DON'T SELL WITHOUT PERMISSION OF THE AUTHOR ! |
| DON'T INCLUDE IN COMMERCIAL PRODUCTS OR ARCHIVES WITHOUT |
| PERMISSION OF THE AUTHOR ! |
| |
| This program is provided "as is" without warranty of any kind. |
| The entire risk of using it is to the user himself. In no event I |
| will be liable for direct or indirect damage, loss of data or |
| criminal actions done due to the use of this program. |
| If you do not agree with this, you must not use COP. |
| |
+-----------------------------------------------------------------------+
_____________________________________________________________________________
The THOR-Software Licence (v2, 24th June 1998)
This License applies to the computer programs known as "COP". The "Program",
below, refers to such program. The "Archive" refers to the the original and
unmodified package of distribution, as prepared by the author of the Program.
The Program and the data in the archive are freely distributable
under the restrictions stated below, but are also Copyright (c)
Thomas Richter.
Distribution of the Program, the Archive and the data in the Archive by a
commercial organization without written permission from the author to any
third party is prohibited if any payment is made in connection with such
distribution, whether directly (as in payment for a copy of the Program) or
indirectly (as in payment for some service related to the Program, or
payment for some product or service that includes a copy of the Program
"without charge"; these are only examples, and not an exhaustive enumeration
of prohibited activities).
However, the following methods of distribution involving payment shall not
in and of themselves be a violation of this restriction:
(i) Posting the Program on a public access information storage and
retrieval service for which a fee is received for retrieving information
(such as an on-line service), provided that the fee is not
content-dependent (i.e., the fee would be the same for retrieving the same
volume of information consisting of random data).
(ii) Distributing the Program on a CD-ROM, provided that
a) the Archive is reproduced entirely and verbatim on such CD-ROM, including
especially this licence agreement;
b) the CD-ROM is made available to the public for a nominal fee only,
c) a copy of the CD is made available to the author for free except for
shipment costs, and
d) provided further that all information on such CD-ROM is redistributable
for non-commercial purposes without charge.
Redistribution of a modified version of the Archive, the Program or the
contents of the Archive is prohibited in any way, by any organization,
regardless whether commercial or non-commercial. Everything must be kept
together, in original and unmodified form.
Limitations.
THE PROGRAM IS PROVIDED TO YOU "AS IS", WITHOUT WARRANTY. THERE IS NO
WARRANTY FOR THE PROGRAM, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
PARTICULAR PURPOSE AND NONINFRINGEMENT OF THIRD PARTY RIGHTS. THE ENTIRE
RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD
THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY
SERVICING, REPAIR OR CORRECTION.
IF YOU DO NOT ACCEPT THIS LICENCE, YOU MUST DELETE THE PROGRAM, THE ARCHIVE
AND ALL DATA OF THESE ARCHIVE FROM YOUR STORAGE SYSTEM. YOU ACCEPT THIS
LICENCE BY USING OR REDISTRIBUTING THE PROGRAM.
Thomas Richter
_____________________________________________________________________________
I) Who should use COP ?
------------------------
- If you prefer working with the workbench or if you write programs in
pascal or (ARGH) basic, if you do not know how to use an assembler
or are not familiar with bits and bytes, if you hate command interpreters
and like funny gadgets and colorful menus, if you do not know the ASCII
character codes by heart :
**======================================================**
|| FORGET IT ! STOP NOW ! YOU WON'T BE HAPPY WITH COP ! ||
**======================================================**
To make it short: COP is intended to be used by REAL MEN ! (-;
(or WOMEN...)
(Suggested: "Real men don't eat quiche" available on
in good networks...)
II) COP Features
----------------
Let's start with the bad ones:
o) it looks like an old-time debugger and feels like one, too
o) there's no graphic user interface
o) it's based on a command interpreter
o) it's hard to learn
o) it should support almost all MC68xxx, although I
haven't tested it
o) some features are available only with additional
hardware, e.g. a MC68010 or higher or an external
terminal
o) some commands are available only with the 2.0 roms or better
o) the build-in terminal emulation isn't a fast one
and uses non-standard command sequences
o) it does not handle fragmented memory models in a
good way, although it's getting better
o) there is no trackdisk or harddisk support and there
never will be
o) it does not use task switching, but busy-waits
(ARGHH!)
Some of the points WILL change in the future, I promise...
...and now the good ones:
o) it does support all members of the MC68000-family,
at least it should...
(MC680000 thru MC68060 including FPUs, and MMUs)
o) it supports the MMU partially.
o) it provides a break key that can be assigned to
any (well, almost any) key on the keyboard
and that breaks almost everthing everytime.
o) it uses hardware resources as less as possible
(e.g. no blitter acesses, no copper on request)
o) COP can be used to remote-debug a system over a
serial connection, leaving the display and keyboard
hardware to other programs
o) COP catches almost all system crashes ("GURUs")
o) COP can be used to debug almost all code, even
interrupts are NO problem (is there a second
debugger that can ?)
o) it can be made resident to debug startup code
o) it supports symbols in its own language and
the symbols in object modules. Source level
debugging, however, is not supported.
o) it has a funny documentation in broken english
(speak you english ?)
o) this new release supports printers, connected either to
the parallel port of your Amiga or to an external terminal,
provided it supports the new COP 5 terminal standard
(see terminal.doc in this archive for more information)
o) it can be loaded to a memory position of your choice,
although the arguments are a bit tricky
o) it's free, at least this release...
o) it steps thru everything, even interrupt code and
supervisor programs. YES, exec's task scheduler is
NO PROBLEM AT ALL.
o) it can be used as a shell calculator and
as a label database.
o) it supports symbols in standard overlay segments
(which other debugger does ?)
o) it supports debugging of CLI/WB progs in C and BCPL
thru a simplified interface
o) it works in really almost all situations, even
with execbase broken...
o) it supports the ShapeShifter
o) it is compatible to the Enforcer and SegTracker if used
with a MC68020 or MC68030, and to "MuForce" for all
processors. It might be compatible to Cyberguard, even
though I won't recommend this program.
o) supports the "Picasso96" graphics system. It's currently in the
"works fine for me" state, feedback welcome.
...and if I say "almost all" I mean: more than any other
debugger can, but I am honest: There are situations where
COP CAN crash, but they are VERY rare.
III) Before you start, you need to provide...
-----------------------------------------------------------------------------
(or, in other words: NOT included in this package...)
- a lot of good will and your brain. COP is not easy to use...
- this manual. Or to make it clear : READ THIS FIRST BEFORE YOU
START PLAYING WITH COP. There's a good chance you'll crash your
system.
- an amiga computer with at least 512K. The more memory, the better.
- If you want that magic break feature : A processor MC68010 or
higher would be fine. The break key does not work in all situations
with the standard MC68000.
- If you need all commands (e.g. task capture and task freeze), you need
commodore's 2.0 roms or better.
- If the program to debug requires the display subsystem, you need at least
an external serial tty terminal - this is the recommended way to debug
programs anyways.
- If you want a fancier and better user interface, the external terminal
should understand type-3 terminal commands or better. Cause this is
a private format, there are not many... :-)
You may write your own terminal, or use the one supplied in this
package, see "terminal.doc".
- If you need printer output, you need either a printer connected to the
parallel port of your Amiga or a printer connected to an external type-5
terminal or tty-terminal with printer-support. Any printer will do, COP
outputs only plain 7-bit ASCII.
Use the following configuration for your printer:
o) data input from parallel interface
o) Auto-LF on, CR disabled (Auto-CR does not care)
This is, however, the most common setting, so just try. The normal setting
will work in most situations without any change.
If you MUST use the Amiga parallel port, use the command line switch
BUILDINPRT or the IOCD.Q command to disable external printing.
The current version of COP is not able to debug a program via the parallel
port, though. It's exclusively reserved for printer output. If your program
requires the serial port, use the build-in terminal emulation.
IV) Installing COP in your system
-----------------------------------------------------------------------------
If you want to remote-debug your system: connect an external ASCII-terminal
to the serial plug. Set the external terminal to the following parameters:
9600 baud, 8 bit, 1 stop bit, no parity,
no auto LF, no auto CR, non-erasing BS
If your external terminal supports printers, connect the printer to THIS
terminal, not to the Amiga; if not, connect the printer to the parallel port
of the Amiga and use the IOCD.Q command or the command line option
BUILDINPRT to tell COP to use the build-in printer-routines.
Copy the COP file to the C:-drawer of your system disk and, if you like to
start COP from the workbench, copy the COP-icon anywhere you want (this is
not required, only a nice feature ).
Copy the shell scripts "Debug","WBDebug" and "Calc" to the S: drawer,
put this file in a save place wherever you want.
If you have commodore's V40 includes, copy the default data description
table "Startup.DDT" to S:. You might want to modify it a bit, for example
to correct the paths. This file currently expects the FD files in a
device FD:, and the includes in INCLUDE:
If you want to run COP with the shapeshifter, copy the file "Mac.DDT" to
S:, too.
Insert in your startup-sequence DIRECTLY FOLLOWING to the "SetPatch"-command
(this is the second line for most systems) a command like the following:
COP keymap usa display resident ddt s:startup.ddt pre s:startup.pre
If you own a 040 or 060 based system, you should specify the "NOMMU" and
"NOEMU" options as well.
What does this mean:
-The build-in terminal uses the keymap "usa". If you prefer a different
keymap, change "usa" to your favourite keymap - it must be present in
the DEVS:keymaps drawer of your system.
YOU CAN'T CHANGE THAT KEYMAP WITH A "SETMAP" or "SETKEYBOARD" or the
PREFERENCE PROGRAM LATER !
COP OPERATES INDEPENDED FROM THE REMAINDING SYSTEM !
-The "display" command tells COP to use the build-in terminal instead of an
external one. You can debug programs with the amiga keyboard on the amiga
monitor. If you want to remote-debug, use "serial" instead. If you've got
an external tty, I would suggest to do so.
-The "resident" keyword tells COP to stay resident even after reset. If
you do not need this feature: drop this argument. Loading COP as resident
program has the advantage that you can debug boot code.
-The "ddt" keyword loads the standard labels placed in the ddt-file and
commodore's include files into COP. If you don't have them:
Never mind, just delete the the last two arguments.
-The "pre" keyword instructs COP to build a pre-compiled image of the "ddt"
file on first startup - they are faster to load and speed up booting. If
you're low on disk space, drop this argument.
-The "nommu" keyword for 040 and 060 systems tell COP not to touch the MMU
unnecessary. The MMU is required for these systems to guarantee reliable
DMA access.
- The "noemu" keyword avoids catching of emulator traps for unimplemented
040 and 060 FPU instructions.
More about the command argument line later... (chapter XI)
You should also start the workbench with the "-debug" option to have COP
ready in all situations.
For professional debugging, you should also install "MuForce" by the
same author, and "SegTracker" and "MungWall", all by Michael Sinz. "MuForce"
is supported by COP, bus errors are routed thru COP, though. The "SegTracker"
is used by COP to find the segment/offset information of a crashed program.
Save the modified startup-sequence and reboot your system. Not much to
see? O.K., that's normal. COP is NOT a standard debugger and is only
INSTALLED by the command line, but not STARTED.
V) How to start COP
-----------------------------------------------------------------------------
There are many ways to begin a debug session with COP:
-Double-click the COP-Icon, if you copied it to your system.
-Enter in the shell the command:
COP go
-Select the "ROMWack" (or "Debug") menu of the workbench. COP replaces
the old wack completly, if there was one installed in your ROM.
(Commodore removed the old ROM-Wack from the 3.1 Roms and replaced it
with the "SAD" debugger.)
-Press the BREAK-key. In the build-in terminal - if you gave the
"display" argument above - this is the decimal dot of the numeric key-
pad. On external terminals, it's ESC. However, you may change that key
with an additional argument, see chapter XI.
-Use the shell-scripts "Debug" and "WBDebug" to load programs,
symbols and start a debug session like with every other debugger.
Up to eight arguments are allowed here as CLI arguments, resp. one as
an extended selection icon "shift-selected" with the main icon.
-The least pleasant way : Your system crashes and COP is entered auto-
matically. There are NO GURUs any longer, COP catches them all !
(Well, almost all... A special DOS crash isn't routed thru the standard
system requesters and can't be captured by COP - sigh.)
If you supply a data description file (see below), you even get the
guru codes in a readable language. If you installed "SegTracker", too,
COP will also present the name, the segment number and the segment offset
of the code that crashed.
VI) How to leave COP
-----------------------------------------------------------------------------
Enter GOPG in the COP command line and press RETURN. This should start
the program interrupted.
If you entered COP by a guru, you should first debug the system or will
get just another guru in mostly all cases. There's no good strategy to
accomplish this task....
You may also start the old ROMWack from inside COP with the EXIT command.
Starting with ROM versions 3.0, the system debugger has changed to the
(more primitive ? different ?) SAD.
See the autodocs how to use this thing...
VII) A word about COP-terminals
-----------------------------------------------------------------------------
You will normally use COP's build-in terminal to debug code, but this
terminal will, of course, need some of the hardware systems - the display
system, i.e. the copper and the display DMA channels (not the blitter),
and the keyboard, also the parallel port if you want to print.
I tried to implement the terminal as best as possible, but this may
conflict with other programs which want to use the same hardware resources.
For this reason COP can also be used to debug a system via the serial port.
All you need - for the minimum configuration - is an external
ASCII-terminal,e.g. a second amiga with a standard terminal program will
do it.
In this case, choose the following transfer options:
9600 baud, 8 bit, 1 stop bit, no parity
no auto CR, no auto LF, nonerasing BS
However, things are much easier if you use a terminal program providing
COP's private terminal formats, here called "type-3" or better terminals.
The terminal transfer standard is documented in the "Terminal.doc" file
in this drawer, if you want to write your own program. There are only
two ready made programs supporting this standard:
-THOR's "Terminal" program for all Amigas provides a type-4 terminal
emulation and is included in this drawer.
Enable the "COP Terminal Emulation" from the menu Settings/Protocol.
You also need to supply a null-modem connector, but you should know
how to build one...
-THOR's "DASB" terminal is a full type-5 terminal, working on
Atari 800XL computers with a serial interface box. It's included
in the package.
There are no settings to be made, DASB is written exclusively to communicate
with COP, but does not support a printer. This drawback arises from the
Atari XL hardware.
If you want to write a COP terminal on your own (e.g for a C64) you
are welcome! Please send me an email in this case (address below).
The build-in terminal for non-remove debugging is of course a full
type-5 terminal.
Here a word about the keyboard processor of the build-in terminal:
I tried to write a keyboard parser not conflicting with other
applications, i.e. it does not read the IRQ-registers of the CIA-
chips and is able to work even with all interrupts disabled. However,
there are "some" drawbacks of this magic stuff : Sometimes a key
may "leak thru" the keyboard parser to other applications. Because
the corresponding key-up event is missing, the keyboard device will
then activate the auto-repeat loop and generate a stream of key-events.
If this happens, leave COP and press the repeating key to stop it.
Even worse, you won't recognise this bug if the affected key is a
control key like "Ctrl" or "Shift". If, after leaving COP, the key-
board seems to be out of order, try pressing all this keys first to
send their key-up events. I tried hard to fix this bug, but it looks
like there's no better way to write a magic keyboard parser. If you
want to use COP the professional way, you should work with an external
terminal anyhow.
VIII) How to enter commands, the line editor
-----------------------------------------------------------------------------
Once you've entered COP, it presents you the prompt "COP >" and is ready
to accept debug commands. Below the special keys used for line editing:
-The backspace key erases the last character entered and moves the
cursor backwards one line ("Delete" on some terminal). On some terminals,
Ctrl-H must be used as a substitution.
-The delete key ("rub-out" on some terminals, Ctrl-Backspace with
DASB, not available on all terminals) deletes the character under the
cursor and scrolls the rest of the line backwards.
-The return key starts the execution of the command ("Enter" on some
keyboards)
-Ctrl-C aborts the execution of a command.
-Ctrl-U re-displays the last command entered - there's only a two-line
history for commands, identical and empty lines will not enter the history.
-The decimal dot on the numeric keypad (for the build-in terminal) or
the ESC-key on external terminals stops execution of code and enters
COP. However, this break feature wouldn't work if all interrupts are
disabled or, if you use the MC68000, the interrupt vectors are messed
up.
-The cursor-forward-key moves the cursor forward one character (only
type-3 or higher terminals)
-The cursor-backward-key moves the cursor backwards one character
(only type-3 and better)
-The cursor-up key moves the cursor to the begin of the line (type-3
and better only)
As a replacement, Ctrl-A can be used for this task with TTY-terminals.
-The cursor-down key moves the cursor to the end of the line (type-3
and better only)
A replacement for this key is Ctrl-E.
-The Alt-Del key or Ctrl-Clear (with DASB) erases the whole line
(type-3 only). This feature is available with Ctrl-B on all ASCII
terminals.
-The TAB-key has a special meaning while entering data sequences and
is described below.
IX) The COP commands and expressions
-----------------------------------------------------------------------------
Each COP command looks like the following:
- a four character command base name or a one character short-cut
- optionally a dot and an extension that determinates a specific
sub-command of a larger command class
- optional arguments each separated by space
ALL numbers accepted by COP MUST BE GIVEN IN HEXADECIMAL, all arguments
may contain simple calculations with numerical operators. This will be
called an EXPRESSION in the following, abbreviated with <expr>.
Here all supported operators, listed by their priority from low to high
(higher priorities are evaluated FIRST, please note that the priorities
differ from C - in special the shift operators):
$ trap operator
a$b returns a if b is faulty, else a.
NOTE: You cannot enclose $ in brackets, so expressions like
(2$a+b)-3 are ILLEGAL !
The reason for this is that COP can't continue to evaluate
expressions with illegal syntax that will be trapped by $
?,: C-style condition operator:
a?b:c returns b if a is not equal, else c
=,<> equal, not equal: returns -1 if expressions to the
right and left are equal (resp. not equal) or 0 otherwise.
>,>=,<,<= signed greater, greater equal, smaller, smaller equal.
Returns -1 if the condition is true.
| binary or
! binary or
^ binary exclusive or (XOR)
& binary and
+,- addition, subtraction
>>,<< shift left or right. The left expression is shifted
times the right expression
*,/,% multiplication, integer division, modulo
[..] indirect operator: the value is the (long) content of
the address specified by the expression between the
braces, e.g. [4] is ExecBase.
[..].l same as [..]
[..].w indirect operator, returns the (sign extended) value of
the word at the address in braces
[..].b indirect operator, returns the (sign extended) value of
the byte at the given address
[..].o the operator size is determinated by the instruction under
the program counter.
NOTE: There is a slight difference if you read a word or a
long from an even or odd address. Reading from an even
address is only ONE memory access, but reading from an odd
one are TWO or FOUR accesses. While not a problem to normal
memory, this is a difference for hardware registers !
(..) normal brackets: expression in the brackets is
evaluated first
- unary minus, i.e. change of sign
~ unary not
> unary greater. This symbol contains the last address
affected by COP and is called the "here" address pointer.
It is affected by almost all commands and can be used
for saying the new command should "work on the same
address" as the last one.
* unary star. This symbol contains the program counter of
the CPU and is equivalent to ".pc"
.b,.w,.l,.o Sign extension operators. Will interpret the preceding ex-
pression as byte, word or long and sign-extend it.
So $ff.b is -1, but $ff.w is $000000ff.
The .o is again the sign-extension to the operator size
of the instruction under the PC.
There is a small, but noticable difference between
[adr].b and ([adr]).b ! The first will read only ONE BYTE
from memory, the later FOUR BYTES but throwing away three
of them. This DOES make a difference if you read a
hardware-register !
.reg
or
'reg The content of the CPU register .reg
or Valid registers are .d0 to .d7 for CPU data registers,
reg .a0 to .a7 for address registers - note that the
meaning of .a7 changes with the supervisor bit -
.ssp and .usp for the two stack pointers
.pc (same as *) for program counter and .sr for the
status register (there is NO .ccr, use proper masking).
Also, there are 16 COP internal counter registers
.c0 to .cf. They are incremented each time they are
read and can be used to implement counter breakpoints.
For some commands .fp0 to .fp7 are valid and address
the eight FPU registers, if a FPU is installed and
used by the program debugged.
All other CPU/MMU/FPU registers are available in the same
way, with one tiny exception for the MMU "root pointer"
registers. These two registers are 64 bit wide for the
68020/68851 and 68030 CPU/MMU and only the lowest long word
containing the base address of the MMU table is read.
If any of the MMU root pointers are written to, the high
long word is set to $80000002, i.e. to setup a short
descriptor MMU table. This is the standard way how the MMU
is used and I haven't seen any program that uses MMU
tables with long descriptors.
.sr,.se,.so
.dr,.de,.do
These pseudo registers refer to the source and
destination effective address of the command under
the program counter.
.sr is the contents of the source register under
the PC, if available
.se is the effective address of the source operand,
if available
.so is either the content of the source register or
the CONTENT of the effective source address
.dr,.de,.do
Same for destination effective address
You may alter all these registers to effect the source
or destination operand of an instruction. Although not
causing an error, changing .se and .de does nothing
usefull.
(Note: This feature is not yet implemented).
Additional, all supervisor registers of the 680x0 series
can be viewed, as long as your CPU does support them,
and will be written back as well as soon as you restart
the program. However, read the special caveats about the
MMU root pointers above. (Except that you shouldn't mess
with the MMU anyways except you're perfectly sure what
you're doing.)
A new special register .vvbr has been introduced
in release 1.32:
The .vbr register refers always to the VBR of the CPU,
but since COP needs this register to operate properly,
you should not change VBR this way. Whenever possible,
check the value of VBR, and if it has changed, write
the new value not to VBR. Use the VVBR instead, and
restore VBR to the value of the label COPVBR. COP will
then filter out its own exceptions and pass the unused
back to the system thru VVBR as if the VBR has been set.
The change of VBR will now be detected by COP if the
interupt check (ENVI.I) is turned on, and the VBR register
can be restored by SETR.V. The autovector table can be
rebuild automatically using the IRQ-copyback mode, enabled
with the ENVI.C command.
\character The ASCII-code of the character following
$ Unary $. The number following is given in hexadecimal
AS THIS IS THE DEFAULT, THIS SYMBOL DOES NOTHING
# The number following is given in decimal, i.e.
#16=$10=10
% The next number is a binary number, i.e.
%1000=$4=#4=4
label A known label will be evaluated. By default there are
only four labels:
AbsExecBase will contain the value 4, thus is
pointing to the pointer of the system
library.
Version Will contain the version of COP as
Version<<16+Revision
COPVBR will contain the interal vector base
setup by COP. VBR should contain this
value.
DO NOT ALTER COP's vector base, use
VVBR instead.
COPVVBR will contain the default position of
COPs virtual vector base.
Some read-only expressions follow:
(Not starting with a dot -> Not a (pseudo) register -> not alter-
able !)
l0 Left button of mouse or fire on joysticks connected to
port 0, returns 0 if released or -1 if pressed
l1 same for port 1
l0 and l1 might be quite useful as conditions in
breakpoints
r0,r1 Right button of mouse in port 0 or 1
m0,m1 Middle button of mouse in port 0 or 1
WARNING ! Some hardware limitation cause that it takes max.
20 msecs to read r0,r1,m0,m1. This COULD be made somewhat faster,
but nevertheless r0,r1,m0,m1 ARE NOT FAST ENOUGH TO BE USED IN
CONDITIONED BREAKPOINTS.
Reading them causes also the POTGO-hardware register to be trashed.
There is no way to save this register back, although
there is a POTGO-read register - this is a hardware limitation.
su,sr Information about addressing mode under the PC. su and du are
du,dr TRUE if the source resp. destination operator of the actual
instruction is used, sr and dr return TRUE if it is a register
and FALSE if it is in memory.
(This is actually not yet implemented)
op Data type of the instruction under the PC, returns
0 for byte, 1 for word or 2 for long, so 1<<op is the
size in bytes of the operator.
(This is actually not yet implemented)
X) List of all commands
-----------------------------------------------------------------------------
Long command Short command possible extensions arguments
HELP ? none none
prints all COP commands to the active terminal
EXIT X none none
If execbase valid, COP is terminated and the
ROMWack is entered. Note that ROMWack works ONLY
with an external terminal (if there is one... it
has been removed from the 3.1 - V40 roms).
REGS R G,E,C,A none
Register dump commands
Without extension: Dumps all common CPU
registers to the screen, dumps fpu registers
if FPU is available and in use.
REGS.G Dumps the guru number
and the address that generated the crash. If COP
was entered the normal way, the guru number will
be zero.
If a data description table was loaded and
gurus were defined, the full name of the
guru will be printed.
If the "SegTracker" is available, COP will print the
name of the crashing program and the segment/offset
location of the PC within this program.
REGS.E Dumps special purpose
registers of newer members of the MC68000 family as
cache-control and MMU-registers. FPU registers will
be included if the FPU is available and in use.
REGS.C Dumps the COP-internal
counter registers (without being incremented)
REGS.A Dumps effective address
of instruction under PC and memory contents, if
available.
DUMP D B,W,L,C,S,G,H,I,Q,Z,D,X,P,O <expr>
Dump memory. If <expr> is omitted, then the "here"
pointer is used as address, otherwise change "here"
to the given <expr>.
without extension Dump memory in the last mode
used
DUMP.B dump memory as bytes
DUMP.W dump memory as words
DUMP.L dump memory as longs
DUMP.G dump a sequence of hardware
bytes. The memory manager gets
overridden by mode.
! This might be somewhat danger-
ous, if you read some toggle
registers !
DUMP.H dump hardware word
DUMP.I dump hardware long
DUMP.Q dump as quad word (=8 bytes)
DUMP.Z dump as single precision
IEEE-numbers.
DUMP.D dump as IEEE double precision
DUMP.X dump as MC68881 extended precision
DUMP.P dump as MC68881 packed decimal
DUMP.O dump memory as size of instruction
under PC
DUMP.C Dump memory as characters.
All unprintable characters are transcribed with a
backslash and the numerical hex value followed.
DUMP.S Dump memory as strings.
All unprintable characters are displayed as a dot.
After dumping a few lines, COP stops and asks you
to press RETURN or SPACE to continue. You may press
here Q or Ctrl-C to abort dumping.
EDIT E B,W,L,C,G,H,I,Z,D,X,P,O <expr>
Edit memory or hardware. If <expr> is omitted, then
edit the address given by the "here" pointer. Else
use the <expr> as address and save it to "here".
In the edit mode, COP presents you the old contents
of the address given. This value is now ready to be
changed with the edit keys (see the last chapter).
Press RETURN to accept the changes made or press TAB
to undo the changes. Press Ctrl-C to abort editing.
BE WARNED! The string "d0" means "contents of register
d0" not the value "d0", like everywhere in COP. To enter
the value "d0", you've to type "$d0". Quite for the same
reason we've "cf" as "contents of counter #f, increment it
when read" and not "the number $cf". The later is "$cf".
Without extension use the last edit mode used
EDIT.B edit memory as bytes
EDIT.W edit memory as words
EDIT.L edit memory as longwords
EDIT.Z edit as IEEE single precision
EDIT.D edit as IEEE double precision
EDIT.X edit as MC68881 extended precision
EDIT.P edit as MC68881 packed decimal
EDIT.O edit memory as size of instruction
under PC
EDIT.G set hardware as bytes
EDIT.H set hardware as words
EDIT.I set hardware as longwords
The difference between the first group and the second
is that the hardware edit commands do NOT read the
hardware registers prior to the user change. Instead,
a zero gets displayed. Node that this is necessary because
some hardware registers are WRITE ONLY.
In all the modes presented above, you may enter a full
<expr> as well as a numeric constant as a new value,
although the length of the <expr> is limited.
EDIT.C edit memory as characters
Here, you may edit the memory as ASCII-characters. You
may use the backslash followed by a hex number to enter
values not available on the keyboard.
EVAL = none <expr>
Evaluate the expression given and print the result.
The result might be a simple number, but very complex
expressions including labels are valid, too.
UNAS = none <expr>
Unassemble code starting with address <expr> and set
"here" to this value. If <expr> is missing, disassemble
at address contained in "here".
The disassembler knows the obcodes of all members of the
Motorola MC68000 family, but the non-MC68000 codes are
marked. FPU obcodes are disassembled as well, and numerical
constants will be disassembled as decimal floating point
expressions.
Illegal opcodes or opcodes that can't be used on the Amiga
(like the TAS instruction) get marked as well.
Depending on your enviroment settings - see the ENVI comand
- some of the addresses will be expanded to known labels.
NOTE: I was unable to test the correct disassembly of the
MMU and MC68040 codes, although it SHOULD work.
If the address being disassembled is the PC, this line
is marked with an asterisk *; if it's the "here" pointer,
the line is marked with ">".
If the address is affected by a break point, a "B" is
inserted.
NODE N L <expr>
Display the node at address <expr>. If <expr> is not
present, use the "here" pointer, otherwise set "here"
to the address of the node.
No extensions The name of the node and its type
is displayed.
L Dump the node as before, but print
additional information COP can gain about that node. COP
knowns most node types defined in the Os and will print
additional information contained in the data attached to
the node.
LIST L M,R,D,I,L,P,T,S,Q,B <expr>
Dump contents of exec-type lists.
No extension Dump the list at given address,
set "here" to this address. If <expr> is omitted, use
the "here" pointer.
B Same as without extension, but
the list is traversed from the last element to the
first. This is sometimes useful if parts of the list
are broken.
M Print exec memory list
R Print resources
D Print loaded devices
I Print software interrupts
L Print libraries
P Print ports
T Print tasks
S Print semaphores
Q Print hardware interrupts
FILL F M <expr>,<expr>
Fill memory with byte sequence starting with first <expr>
and to last <expr>, exclusive. If one of the <expr> is
missing, then "here" is used. Then "here" is set to the
first <expr>.
without extension Enter the byte pattern the memory
should be filled with. Press TAB to complete one byte, press
RETURN to complete the whole sequence and to start filling.
Again, "d0" is the register, not the value. The number is
entered as "$d0".
M Fill memory thru mask (stencil
fill operation). Enter first the byte sequence
as described above, then enter the mask bytes. Each
bit set to zero in the mask will protect the corresponding
memory bit from a change.
You may press Ctrl-C any time to abort the operation.
FIND I M,I <expr>
Find byte pattern, masked, or find instruction starting
with given address or "here". Set "here" to given
expression afterwards.
The found values are either dumped in the last mode used
by the "dump" command, or disassembled with the "I" mode.
Furthermore, if the display is split, COP stops the search
as soon as something is found and updates the top window
of its screen, with the "here" pointer set to the found
address. This is most useful for displaying a large area
around the found bytes, and can be optained by displaying
the output of a command like "d >-8" in the top window.
To remind you, ">" is the name for the "here" pointer.
More about display splitting is found below.
without extension Enter the byte pattern byte for
byte pressing TAB after each byte and RETURN to complete
the sequence you are searching for.
See above for caveats! "d0" is a register, not a number!
M Find masked. Enter the byte pattern
you are searching for and then the mask.
Each bit left to zero in the mask will disable the
comparision of the corresponding bit in the sequence, i.e.
the corresponding bit in the byte pattern will be ignored
and will match always.
I Find instruction. Enter the
instruction or part of instruction you want to search
for and press RETURN to start the search. Case and extra
spaces will be ignored.
You should note that all known labels will be expanded
by COP unless the enviroment is changed. So you should
enter the label names instead of the address if you look
for an access to a defined label !
You may press Ctrl-C to abort the searching at any time.
MOVE M none <expr>,<expr>,<expr>
Move source memory block starting with first <expr> and
ending with second argument exclusive to destination
given by last <expr>. If any of the <expr> is missing,
"here" will be used. Afterwards, "here" is set to the
start of the source memory block.
Overlapping memory blocks will be handled correctly.
You may press Ctrl-C to abort the operation.
TASK ! F,W,S <expr>
Task commands: display,freeze and warm tasks, send
signals.
without extension Display information about the task
if <expr> is omitted and execbase is valid, the active task
will be displayed.
F Freeze the given task (exclude from
execution). If the task to be freezed is the active one,
this command will work with Kickstart releases 2.0 or higher
only.
W Warm the given task (include a
previously freezed task in task switching).
S Send a signal to a task. You need to
supply two arguments, FIRST the signal to be send and
SECONDLY the task affected.
SETR S F,E,D,V <expr>,reg
Set <expr> to given CPU register.
without extension Move given expression to a
destination register. All CPU registers are valid
destinations, but only the low long word of the 64 bit
wide MMU registers of the 68851/68030 will be set, their
high-longword will be set to $80000002 always. This
word is just a dummy for the 68040 and 68060, but used
to identify the size of the descriptors and a "limit" value
for the 68851/68030. However, I don't remember any program
that makes actually use of these extensions.
If you need to change the vector basis register VBR
of 68010 or above, you should change COP's virtual
VBR called .vvbr instead to keep COP's exception
vectors untouched.
F Load FPU register, if FPU is
available and in use by the program being debugged.
In this case, <expr> is a floating point number in the
usual notation (e.g. 3.1415 or 3E8 ...).
E With MC68020 or higher: enable
all caches. No arguments need to be supplied.
Warning: Don't touch the cache for 68040 or 68060 systems,
at least don't try to activate it by force if it is not
activated. DMA related device I/O might break by enabling
the cache in an I/O operation.
D With MC68020 or higher: disable
all caches. No arguments taken.
Cache finetuning, if required, should be done by modifying
the cacr register directly.
V With MC68020 or higher: Set the
virtual vector base address to VBR, setup VBR to point
to COPs interrupt vector table. This command should be
given (if it isn't already too late...) if a program
changes the VBR to give back control to COP.
STEP Z none <expr>
Enter trace mode, start tracing at given address or use
PC if <expr> is omitted.
How the trace mode works depends highly on the terminal
type used to debug.
On pure ASCII-terminals, the command at the PC is being
disassembled and dumped to the terminal; on type-3 or
type-4 terminals however, an entire page of instructions
is printed. The command at the PC is marked with an
asterisk and is highlighted on type-4 terminals. Lines
with breakpoints are marked with a "B". The current
position of the "here" pointer is marked by ">".
With both types of terminals, COP is now ready to accept
one of the following step commands by pressing the
desired key:
Q or Ctrl-C Abort trace mode and return to normal
command line.
S or SPACE Step the command at the PC. If this is a
subroutine call, the subroutine itself will be entered in
trace mode and can be stepped thru.
T Trace the next command. The only difference
between S and T is how subroutines are handled. With the T
command, the subroutine is called as it and will be exe-
cuted as whole without beeing stepped thru.
N Next command. Almost like T, but works
different with branches. The next command starts the program
at the current PC and COP regains control only if the
statement IMMEDIATLY FOLLOWING the traced statement gets
executed. This will be the same as T for all commands but
branch and jump commands. You may use N to step thru a
loop as whole if you press N for the end condition branch
of a loop.
WARNING !! If this loop has a second exit point, the
command after the end condition may never be executed and
COP is never entered again.
WARNING !! The next command works ONLY IF THE STATE-
MENT IS IN RAM CODE and DOES CHANGE parts of the code by
setting an internal breakpoint. See BRKP-section for a list
of caveats of breakpoints.
M Trace until. Almost like T, but the mecanism
how COP regains control after a subroutine call is different.
The 'T' trace changes the return address to COP's entrypoint.
Sometimes this is unwise cause this address might get used
by the called procedure. If you use 'M' instead, the called
procedure will be stepped thru in 'S'-like behaivor using
the CPU's trace-bit. Of course, 'M' will be much slower
and should not be used if some piece of hardware is accessed
or timing is vital.
O Skip command. Do not execute the command
at the PC and switch PC to the command following.
WARNING !! Make sure that the command skipped does
not anything important and watch out for side effects,
e.g. skipping a "push long to stack" could be dangerous
if the corresponding stack cleanup command is not skipped
too.
G Start program at current PC, activate all
breakpoints.
R Dump registers to terminal.
B Set breakpoint at current PC address.
Note that commands with a breakpoint on it are marked
with a "B". Further, a breakpoint under the current PC
is "delayed", i.e. it isn't activated unil the the PC
leaves its address.
The breakpoint set by "B" will be an unconditioned type
(see BRKP for more about breakpoints)
A Alter display. If working with the build-
in terminal, the COP display is hidden and the display of
the program is brought to the monitor. The "A" command
is like the "IOCD" command without extension, read this
chapter to find more about COP displays.
If you use the remote-debug feature, this command does
nothing.
F Set COP to foreground mode, i.e. COP does
not hide its display if the program being debugged re-
gains control. Press F again to activate the normal display
swapping. This command works mostly like the "IOCD.F"
command, read the "IOCD" section for more information about
COP foreground and background mode.
Some caveats about tracing are:
-------------------------------
- COP does not depend on exec-like task switching, it
is NO PROBLEM to step thru exec's task switching procedure.
(This is actually not a caveat !)
On the one hand a nice feature, on the other hand a problem
if you want to debug a SPECIFIC task. Therefore, you should
trace (T command) over a Wait() or Signal() call of exec.
The NEXT (N command) will work too, but if the same code
is used by two tasks - think about the trackdisk code - you
may catch a different task afterwards. Same goes for the
'M' command, but let me remind you again that 'M' is SLOW !
-The second problem with task switching is that if an exec
task looses control by stepping thru the task-switch
routine, exec will save its status register with the trace
bit on. If the task is reactivated later, COP will regain
control over this task. While not a problem to COP, this
behaviour might somewhat confusing to you, if COP is
suddenly (probably after hours...) reentered - and not by a
guru.
-There's one extra problem with the trace (T) command :
This commands works by altering the return-address of a
subroutine call. Some programs use this return address to
fetch data following the subroutine call and adjust the
return address afterwards. If changed by COP, this
will cause a nice crash of your system. Thus, if you find
funny code behind a subroutine call, e.g. many illegals
or the like, STEP thru this procedure or use 'M'.
-Since stepping thru a procedure is much slower than
executing one, there may arise timing problems in some
critical IO-procedures. You should trace this kind of
subroutines to avoid such problems. This goes again for
the 'M' command, since this is nothing but "automated
stepping".
(That looks like a lot of "features" of this debugger,
but they are typically for this class of programs.
However, most authors handle them as "undocumented
features", but I don't. :-) )
BRKP B A,D,C,R,S,O <expr>
Breakpoint commands. The address affected is given by
<expr> or by "here", if omitted.
without extension If no breakpoint is set at
supplied address, a unconditioned breakpoint is set there.
If a breakpoint is set at this address, the breakpoint
is removed. Note that COP supports up to 32 breakpoints.
It is further important to note that after setting a
breakpoint, it is not yet active, i.e. causes a COP inter-
cept. The breakpoints are activated each time a program is
restarted, e.g. with the GOPG command; they will get de-
activated each time COP is entered again to prevent an
endless loop if a breakpoint is set in interrupt code.
However, the breakpoints can be activated by hand, although
this is not recommended.
BRKP.A Remove all breakpoints (no
arguments accepted)
BRKP.D Display all set breakpoints
with conditions, no arguments accecpted.
BRKP.C Clear breakpoint at given address
BRKP.R Reset all COP counter registers
.c0 to .cf to zero.
BRKP.S Set breakpoint at given address
and condition, if any. If the condition is omitted, then
an unconditioned breakpoint is set. If a counter
register is included in the condition, it is reset to zero.
With a conditioned breakpoint COP is entered on a BREAK
hit only if the condition is true, i.e. not zero.
You should remember that a counter register is incremented
each time it is accessed, so you may use this feature
to implement counter breakpoints, e.g. ".c0>=5" will stop
execution after the fifth BREAK-hit.
BRKP.O Activate all breakpoints (no
arguments accepted). Note that this operation might
somewhat dangerous if a breakpoint in an interrupt
procedure gets activated. In this case, COP will display
its "COP crashed" or "Other Task Crashed" message...
have fun!
Some extra features of breakpoints are the "delay" of
breakpoints and the automatic removal of them:
-If you set a breakpoint under the current PC, this
breakpoint won't get active if you start the program,
but gets activated AFTER the PC leaves the statement.
This is useful cause you usually never want to break
on a command you already broke on. You will enter COP
when the program reaches the breakpoint again.
-If an already activated breakpoint is getting written
over by a program (e.g. the memory is freed and another
task re-uses this area), this breakpoint is REMOVED
automatically at the time COP is entered again.
This is done to prevent programs from crashing by dangling
breakpoints of a program that is no longer in memory.
WARNING ! The breakpoint IS NOT removed, if it
is not active at the time it is written over.
This MAY cause problems if the program changes and the
breakpoint is re-activated later, e.g. the breakpoint
may change the address part of a jump-instructions,
possible resulting in a nice fireworks display...
WARNING ! Active breakpoints change the code
at their address to the ILLEGAL obcode. For this,
BREAKPOINTS DO NOT WORK IN ROM.
(Trick for MMU owners if you need to do this: Enable
the MMU bypass and set the breakpoint in the mirrored
RAM.)
Second, if the code is changed, possibly some check-
sums (for libraries or resident code) will change and
things won't work later. For this reason, use the
T S or M STEP subcommands to step thru this part of code,
they DO NOT ALTER the code and work in RAM as well as in
ROM.
GOPG G U,T <expr>,<expr>
without extension Start interrupted program at given
address or at PC if <expr> is omitted. If any breakpoints
are set, activate them first. A second argument is not
accepted.
U Go until
Set a breakpoint at the first given <expr> and start
the program at the address given by the second argument,
or the PC if omitted. Read the breakpoint section about
caveats of breakpoints !
T Trace until
Step thru the program until the PC reaches the first
expression. The second expression will be loaded into the
PC if given. This will be very slow, like the 'M' sub-
command of STEP.
CAPT C S,N,C [<expr>,]<expr>
Capture a task, i.e. start debugging it.
no extension Capture the task with task
structure at the supplied address. If <expr> is omitted,
"here" is used. Afterwards, "here" is set to the
affected task address. If the task uses the FPU,
this capture command will work only with Kickstart
release 2.0 or later, due to the private exec stack frame
which has been changed in Rev. 2.0.
S Like capture without arguments,
but the first argument you supply is a signal mask which
is send to the task before trying to capture it. The
second argument is the address of the task structure.
N Capture the next task getting
started. No argument must be supplied with this sub-
command. Note that you might find the new task in the
private dos startup code you have to step thru first.
C Capture next command getting
started from the shell. This command works only with
Kickstart 2.0 or later.
IOCD O S,C,B,F,R,Z,L,M,V,P,Q,I,E <expr>
Input / output commands, terminal commands (rather a
lot of them...)
without extension (does not take any arguments)
If you work with COP's build in terminal, toggle between
COP's display and the display of the program being de-
bugged. This is not done by intuition or the like, but
by PURE HARDWARE. For this reason, COP needs to know the
address of the copper list of this program, and with the
ECS-chipset, the BEAMCON0 value. While both is available
in the graphics library, you must set them by hand if
execbase is destroyed or the program debugged uses the
hardware register to setup its display.
While COP can almost always establish its screen, it is
sometimes impossible to restore the programs screen
completely - some hardware registers are write-only.
In this case, you MUST use remote-debugging.
If foreground or background mode has been active (see
below) they are deactivated by the IOCD command.
IOCD.S (does not take arguments)
Toggle between build-in terminal and remote-debugging.
If you switch to an external terminal, you should make clear
that this terminal is online, or you might fail to enter
a second IOCD.S to switch back to the build-in one.
Everytime the terminal is changed, COP retries to get the
terminals type to setup type-3 or type-4 communication.
For more information about COP's internal terminal format
and auto-identification read the "Terminal.doc" file
included in this drawer.
IOCD.C <expr>
Set the address of the copper list of the user-program to
re-establish the user's display. If <expr> is omitted,
the "here" pointer is used. You won't need this command if
you debug programs that use the "standard" graphic system,
since COP extracs the address out of gfxbase itself. But
if the user's program uses the hardware registers directly,
COP does not recognize this change of the copper list.
In this case, search with the FIND command for a write to
the hardware register and set this value as user-copperlist
with IOCD.C <expr>. It is seldom easy to find it, so
good luck...
If you have problems with programs using custom copper
lists, you should try the interrupt driven display using
the IOCD.I command (then you get trouble with
interrupts instead of copper lists... ;-)
IOCD.I (does not take arguments)
Toggle between copper list driven display and interrupt
driven display.
The standard way for COP to display information is to
setup a copper list and to load it into the hardware. Later
on, if the program is started again, the system copperlist,
which can be set by IOCD.C, will be loaded back.
This will, of course, cause trouble if the program changes
the copper list on its own.
The best solution is of course to change to remote de-
bugging using IOCD.S, but startig with release 1.30 COP
can be forced to use a different method of display.
The interrupt driven display does NOT use copper-lists,
but uses the vertical blank interrupt to write the
hardware registers. COP tries its best to keep the program
setting valid, e.g. if the program disables the interrupt,
COP excludes the user VBI from running. However, this is
really a bit tricky and may fail. A second drawback is
that the display produced by interrupts is much simpler
and does, for example, not support line highlighting.
IOCD.B (does not take arguments)
Set COP to background mode, i.e. COP's display is never
setup and the users display is kept active. However,
you are still ready to enter commands. This mode is
somewhat impracticable since you don't see what you type.
IOCD.F (does not take arguments)
Set COP to background mode, i.e. COP's display is not
removed from the monitor (only execption: a GOPG command
or the G subcommand of the STEP-command). Use this command
to avoid the flicker that occurs if the screen changes.
There's one caveat with this command and the STEP-command:
Since the displays are not swapped, the user program may
destroy COP's display by writing to a hardware register or
may get unexepected results reading a register while COP's
display is active.
So watch out and disable the foreground mode if you want
to step this type of commands.
IOCD.R (does not take arguments)
Disables foreground and background mode and restores
normal display swapping.
IOCD.Z <expr>
Set the screen size of the build-in terminal to <expr>
lines. If <expr> is omitted, the actual display size
will be used.
The standard screen size is 28 (=$1C, remember COP always
thinks in HEXADECIMAL !) lines, but this might be too
large for some monitors. To prevent you grabbling at your
monitor, this command can be used to setup a fitting
display size. However, the screensize is limited to 8 to
28 lines and will always be centered.
IOCD.L <expr>
Setup the number of lines until COP presents its ***more***
message to ask for continue. This number is more an
approximate value as some outputs can't be broken up into
lines (for example the register display does never generate
a ***more*** message).
If <expr> is not given, the command uses the last value.
(Remember that COP thinks in HEX, so 10 is not TEN but
SIXTEEN !)
IOCD.M <expr>
Set the value to be written to BEAMCON0 if user display
should be rebuild. This command is not required unless
an application uses the hardware registers directly.
See IOCD.C and IOCD for more information about this
feature.
If possible, COP tries to build a NTSC-display because
it is less flickering than a PAL screen. I think there
should be no problems with this feature, even commodore's
@#!?!-monitor supports 60Hz displays and most european
TVs will do so, too. If there are problems, use the next
option to use a PAL display instead, or use the PAL
command line option (see below). Some flicker fixers
might have problems with the long/short frame toggling
of the NTSC display, COP offers the PAL60 option.
IOCD.V (does not take arguments)
Toggles the display mode between NTSC, PAL and PAL60.
ECS or better is required for this function.
IOCD.P (does not take arguments)
Toggles printer output.
Not all commands cause a printer output, e.g. the edit
and step commands do not, since they are interactive.
IOCD.Q (does not take arguments)
Toggles printer support via the build-in printer driver
thru the parallel port of the amiga or the terminal
connected to COP (this is the default).
If you use the build-in terminal emulation, this command
will make no difference at all, but with an external type-5
terminal COP will either print itself or tell the external
terminal to start or stop printing. The later method is of
course the better one, it does not take over the parallel
port hardware.
All IO-commands but the L,S,P and Q subcommand don't make
sense in a remote-debug session and don't do anything in
this case.
IOCD.E (does not take arguments)
This command does not take any arguments. It will send a
FORM FEED control character to the connected printer, to
eject the paper. This might be needed by some laser or
deskjet printers.
ENVI V R,L,I,B,X,E,M,F,D,C,U,O <expr>
Enviroment settings, mode settings and so on.
without extension Not valid. This command MUST
be extended.
ENVI.R (does not take arguments)
Enter raw mode. In this mode,
execbase is not used at all. There are much consequences
of entering the raw mode: The display copper list and
beamcon0 must be set by hand (with IOCD.C and IOCD.M),
interrupts are disabled if COP is entered, all list
commands depending on exec-lists, all task commands and
all capture commands refuse to work. The EXIT command
is not available, too. The SegTracker interface will be
disabled, too.
There is no message if these commands are still entered.
All exceptions except interrupts cause now COP to inter-
cept, even if there is an exception handler installed in
the active task - normally it's no problem to run COP
parallel to a "normal" debugger, but in RAW-mode COP will
capture even its breakpoints.
If you've entered the raw mode once, there's NO WAY
TO SWITCH IT OFF LATER except a power up or a reboot,
so be careful !
You should use the raw mode if you MUST debug a program
that uses the hardware directly. In most cases, it is
necessary to use remote debugging, too.
If you must use the chip-mem buffer, you are REQUESTED TO
USE the raw mode too, or you will run into BIG TROUBLE
with task switching activity.
ENVI.L <expr> <expr>
Add memory section. Cause COP does not use the exec
memory list, COP tries to find the memory portions
in your system on startup, i.e. chip mem, fast mem
and the kickstart ROM. However, COP cannot handle
"too complicate" memory models, e.g. fast mem that
is split in several blocks or memory that is not
aligned to 64K borders.
To fit your needs, you may add a memory chunk of
your choice to COP's list.
The first argument specifies the start address of
the block, the second the (exclusive) end address,
if both are equal, this memory block will be removed
from COP's private list.
This memory list is used for the FIND and FILL commands,
memory is scanned for all addresses in it.
NOTE: Normally, the memory in an Amiga is
typically not organized in a linear way, some memory parts
are mirrored to others and the memory is possibly split
into some chunks, e.g. if you have a memory expansion
card in an old Amiga 2000B with ranger-memory (slowmem).
In this case, your fast mem will fill the addresses
0x00020000 to ??? and 0x000c8000 to 0x000d0000. In this
case COP will search the total area from 0x00020000 to
0x00d00000, including some hardware registers in between.
In this release, COP can not handle such complicated memory
models, maybe later...
(This is even better than pre-1.17 releases, which were un-
able to work with A4000 memory models at all....)
ENVI.I (no arguments)
Disable the checking of changes of IRQ-vectors.
Under normal conditions, COP checks the consistency of
the MC68000 autovector table, used by COP to allow trace and
breakpoint commands. If one of the entries are changed,
you will be prompted by a message if it's O.K. to undo the
change, to accept it (in this case COP writes the change
back to its second vector table, which can be used by
ENVI.F), or to ignore one or all changes.
This change could be done by a faulty program, or
by a program that wants to regain control over the whole
system. In the first case it's better to answer U(ndo), in
the later C(hange). If you use a MC68000, the address in the
trace and illegal trap vectors are vital, and any change
of them will prevent COP from being able to step thru
programs. Also, COP needs at least one interrupt that
occurs "often enough" to check the status of the break key.
With a MC68010 or higher things are not that worse, cause
COP uses the VBR register to move the autovector table
to a different part of the memory. However, changes to
the old table will be respected, although COP does not yet
notice the change of the VBR register. In case you notice
that the VBR has been changed, set it back to the old
value which can be found in the label COPVBR and place the
new value in the virtual vector base called VVBR.
If you disable the IRQ-checking, all changes to the
autovector table are ignored.
ENVI.C (no arguments)
Enables the IRQ copy back mode.
Instead of watching the low-memory vector base, COP keeps
an eye on its own vector offset and copies the changed
vectors on request to the virtual vector base. This option
should be choosen if you want to debug a program that
directly writes to the vector base, like ShapeShifter.
The command line option "MacMode" enables this automatically.
Be warned: Enabling the copy back mode disables the check
for the low memory vector table, which is normally used by
the Amiga OS.
This check can be disabled with the ENVI.I switch described
above and works of course only for the MC68010 or better.
ENVI.B (no arguments)
Toggles the ChipMem backsave buffer.
The display build up by COP's internal terminal emulation
needs some chip memory that might be occupied by the
program you want to debug. If you want to prevent COP
from overwriting this area, you must:
o) provide a backsave area using the BUFFER keyword on
the command line when COP is installed
(usually in the startup-sequence)
o) enter the ENVI.B command to enable this buffer
o) you SHOULD use the Raw-mode to prevent conflicts with
multitasking
If the buffer is enabled, COP will backup the occupied
memory area each time it builds its own display and will
restore it, if the program's display is restored later.
However, this backup mechanism is not (yet) fully trans-
parent to other parts of COP, but the UNAS and DUMP
commands keep care. It will be therefore convienent to
place COP's CHIP hunk an uninteressting part of memory,
e.g. the display buffer of the debugged program would be
fine. To prevent problems with the blitter, COP will wait
for the blitter to complete before swapping the memory.
In all other cases the blitter will be just stopped.
ENVI.X (no arguments)
Affects the way the disassembler handles the indexed
indirect mode with label generation. The default is, that
the address which is used for label generation is given
by the base register plus the index. This is most com-
fortable if, for example, all entries of an indexed table
have labels associated to them. If, however, you want to
reassemble a part of code, this would be fatal since
all assemblers calculate the displacement, which will
be replaced by the label, as a distance to the base
register without the index. So if you switch out the
index inclusion, you will only see labels associated
to the base of a indexed table.
ENVI.E (no arguments)
Toggle the label generation on or off. If you do not want
to see labels, for example in a search process looking for
a instruction with specific address, you can switch out
the label generation at all using ENVI.E
ENVI.M (no argument)
Toggle the build-in memory manager. This part of code
in COP protects you from writing into hardware and non-
existing memory, as well as it does the memory re-
mapping for the chipmem-buffer. If, for special purposes,
you want to disable this feature, use ENVI.M
ENVI.F (no argument)
Toggle the place where the exception vectors are stored.
The default location is at address 0, but since this is
chip memory, exception handling gets slow. If you use
ENVI.F, the vector base will be located in the fast-memory.
Warning! ENVI.F does NOT change the vector base register
at all, since it is pointing to COP's own vector base at
any time. Instead, it says COP where to look for the system
vectors, so it changes only the virtual vector base VVBR.
Warning ! ENVI.F will overwrite the virtual vector base
register VVBR of COP in order to work ! So do not use this
command if you setup your own VVBR.
This command only takes effect if running under a MC68010
or better, since the plain MC68000 does not have a VBR.
ENVI.D (no argument)
Toggle the default input radix, with is set up as hex,
to decimal and back.
ENVI.U (no argument)
Toggle the MMU bypass. All COP memory accesses usually by-
pass the MMU of the 68020 or higher processors, so you see
the true physical addresses. This can be disasterous if COP
is used on an A3000 because disabling the MMU disables the
image of the OS, too. Use ENVI.U to tell COP not to touch
the MMU. That will have, however, certain consequences:
First, all addresses shown in COP will be logical addresses,
not the pure physical addresses. Reading or writing
non-existant or pure system addresses with MuForce
enabled will cause COP to crash by a bus error (that's harm-
less for COP, but you won't be able to alter these addresses
at all).
The command line option NOMMU can be used to enable this
option by default. In any case, be careful with it.
ENVI.O (no argument)
This is a 060/040 specific setting. It selects whether COP
should bypass the non-implemented instruction exceptions
to the 68060/68040 library or capture them itself.
The command line option NOEMU does quite the same, namely
enabling the bypass.
It is, however, not yet clear if this option works or makes
any difference at all. *sigh*
SPLT / C <expr>
This command is available ONLY if you use the build-in
terminal or an external type-3 or type-4 terminal. It
won't work with a raw ASCII-terminal.
COP has the ability to split off a part of the screen for
displaying some information permantly. This information
in then updated each time you enter a command or COP
looses or regains control over the system. For example,
splitting the screen and displaying the register set in
the upper part of the screen while tracing is highly use-
ful and is nowadays standard for all debuggers.
Cause COP is "a little" different from "the common
debugger", you must enable this feature by hand, and due
to the raw display system, it's not available in general -
a raw ASCII terminal can't split the screen.
without extension COP displays a new prompt and you
should enter a command that shall be executed each time
the display must be updated. The output of this command is
then displayed in a separated part of the display.
It is possible to execute more than one command if you
separate the commands by colons.
The argument following the SPLT-command determinates the
approximate size of the split-off part of the display
(in lines; remember that all numerical values are HEX-
VALUES by default !). If there's not enough room, not
all commands will be executed.
There are a few caveats to remember when using the SPLT-
command:
-Not all commands are splitable, e.g. the SPLT and the
STEP commands (since that doesn't make sense at all...)
-Some commands are splitable, but it's not very useful
to split them, cause they get executed each time the
display is updated, e.g. the GOPG and the EXIT commands.
-Almost all commands change the "here"-pointer. This is
NOT true for commands executed in the split-window, i.e.
they can READ "here", but do not change them.
This is somewhat useful since, while tracing, the "here"
pointer contains the address of the first command of the
lower window, e.g. splitting the command "d.w" will dump
the obcodes of the program in hex.
Some useful commands for splitting:
REGS will present a auto-updating register dump
NODE .a6 will print the name of the library pointed
to by a6
DUMP.L .a0 will dump the memory pointed to by a0.
(display will change if a0 changes, of
course)
(Remeber that you should supply a dot in front of the
register names to distinguish between registers and
addresses)
Remember that you can execute more than one command once,
e.g. REGS:NODE .a6
Another idea about splitting is to use it when searching.
COP halts now searching as soon as something is found and
refreshes the split-off command, with the "here" pointer
set to the found command. Thus, splitting the screen with
a command like "u >-8" will disassemble the region around
the found byte everytime the search succeeds.
SPLT.C (no arguments accepted)
Remove the split window and return to normal operation.
NOTE:
This command is always executed if a part of COP causes
a crash. Mainly because this part could be the split-off
command, creating an infinite loop of crashes when re-
freshing the screen after the crash-message.
SKTB T <expr>
Stack traceback.
Search the stack at the given address or at the address
given by the active stack pointer for data- and
code addresses. This will be useful if you want to find
out which part of code called a faulty procedure.
COP TRIES to find out if the data on the stack is
just garbage (which won't be printed) or a pointer
to data, or a return address to a piece of code.
In the later case, it tries to find a label near that
code address, to provide you with the name of the calling
routine.
LABS A E,S,B,G,T,V,A,U,L,F [name]
Dump labels.
This command prints informations about label definitions
loaded into COP. A line dumped by this command will look
like the following:
label name : value (+ base) (flags)
Some labels are either relative to a base, which is printed
in hex if so, or relative to an exec node. It's name is
printed in this case.
The characters in the brackets specify the type of the
label:
A absolute address
E equate. An easy to remember expression representing
a number.
N an address relative to a node, thus, an offset.
V a function vector of a library or a device.
R an offset relative to an absolute base.
S a size of something. Currently not supported.
B a bit definition.
L A lineA trap definition (not required by the
Amiga-OS, but by the Mac OS)
s A COP internal (system) label. There are currently
only four system labels.
r A read-only label.
k A resident label, can't be removed with FLUSHALL
t A temporary (so, user) label. Can be removed with
FLUSH.
The "name" argument specifies the label you'd like to know
information about. Wildcars are welcome here, COP knows
only two wildcards, '?' for one unknown character and '*'
for a sequence of unknown characters. If you don't give a
name, COP selects "*" for you as default, i.e. will show
all label.
The extensions specify the type of labels in the list:
LABS.E [name]
Dump equates only.
LABS.S [name]
Dump only sizes.
LABS.B [name]
Dump bit definitions.
LABS.G [name]
Dump gurus.
LABS.T [name]
Dump line-A traps.
LABS.V [name]
Print function vectors.
LABS.A [name]
Print addresses. Absolute, relative or node relative.
LABS.U [name]
Print all user defined (temporary) definitions.
LABS.L [name]
Print all definitions.
LABS [name]
Print all user defined addresses.
LABS.F <expr>
Find the label nearest to and behind the given address.
This is useful if you know only the absolute address in
memory and want to relate it to the name of a subroutine
of your program.
SEGM Q <expr>
Find segment offsets.
This command takes a memory address and tries to find out
the program this memory belongs to. If successful, COP will
print the segment (=hunk) number of that program, and the
offset within that hunk the given address belongs to.
Michael Sinz' "SegTracker" must be active for this service!
XI) COP arguments to the command line and ToolTypes for the Workbench
---------------------------------------------------------------------
Here a list of arguments COP acceptes as arguments when getting started
from the shell. However, it's possible to start COP from the workbench
and to supply the same arguments as tooltypes. Simply create a tooltype
of the same name for each keyword.
KEYMAP <keymap> Set the keymap COP should use for the build-in
terminal. Please note that you CAN NOT change this keymap with the
SetMap or SetKeyboard command. This keymap is of course not used for
remote debugging.
The keymap file is searched in the DEVS:keymaps drawer (not in KEYMAPS:
cause this logical device is not standard with Kickstart 1.2 or 1.3)
or in the keymap.resource. You need to supply AT LEAST AT STARTUP
a KEYMAP argument to define the keymap COP shall use. (There's no default
in this release, a missing keymap argument will result in an unusable
build-in terminal)
SERIAL Choose remote debugging
DISPLAY Choose build-in terminal for debugging
Note that you MUST supply the DISPLAY argument if you want to enter COP
by a shell command or COP will switch to remote-debugging.
LINES <number> Set the number of lines of the build-in terminal
screen, the default is 28. This argument will be ignored if COP is already
loaded, use the IOCD.Z command instead.
BREAKKEY <number> Set the keycode (NOT the ASCII-value !) of the
BREAK-key. This value will be used only by the
internal terminal emulation and will be ignored
under remote debugging.
Some useable keys (in other words: You
MAY use the return key, but...) are:
93 the asterisk on the numeric key pad
90 the braket-left key on the pad
91 the braket-right key nearby
74 the minus key on the pad
94 the plus key underwards
60 the dot on the key pat
this is the DEFAULT.
You may also use hex numbers if you place a $ or a
0x in front of them.
RESIDENT Load COP resident into memory, i.e. COP will survive
a reset if execbase is still o.k. and need not to be reloaded. This option
is useful if you want to debug startup-code. If used together with
MuForce, you might want to give the "RESTOREVBR" keyword as well, see
below.
REMRESIDENT Remove COP from the resident list and free all its
memory. Cause COP can not be removed completely, RESTART YOUR COMPUTER
IMMEDIATLY AFTER EXECUTING THIS COMMAND. Some code may write over COP's
still installed interrupt code resulting in a fireworks display or a crashed
harddisk (oh what a fun...).
GO Start a debug session using COP.
BUILDINPRT Use the build-in printer support thru the parallel
port of the Amiga instead of the external terminal printer support. This
option works like the IOCD.Q command.
TERMINALPRT The counterpart of BUILDINPRT: Use the printer pro-
vided by the terminal connected to COP. If you choose the build-in terminal
emulation, this won't make any difference. However, if you debug with an ex-
ternal terminal, the printing will be done thru its port and not thru the
amiga parallel port.
IRQDISPLAY Select the buildin-terminal emulation, switch to
interrupt driven display. This acts like the IOCD.I command.
COPPERDISPLAY Select the copper driven display as default.
IRQCOPYBACK Select the IRQ copyback mode: COP does not watch the
low-memory interrupt vector table, but its own vector table and will copy
changes to the virtual vector base. This is the command-line counterpart of
the ENVI.C setting.
NOIRQCOPYBACK The default operation of COP: Watch the standard
interrupt vector table, which is located at address 0 and up. Both checks
can be disabled with the ENVI.I switch.
RESTOREVBR Instruct COP to re-install its own vector base
register. This keyword is needed if COP is made resident and used in con-
junction with "MuForce". Since "MuForce" installs its own vector base table
on top of COP, a resident copy of COP won't be able to capture enforcer hits
any more. Use this option to restore the VBR of COP, right after
installing MuForce.
MACMODE This macro switch enabled some options and settings
required for COP to run safely under the "ShapeShifter" Macintosh emulator.
SET60 Tell COP that a MC68060 processor is in your system,
although exec.library does not know. The standard Amiga OS 3.1 does NOT
recognize a '60 processor, the correct flags are usually setup later by
a tool provided by the hardware manufacturer, mostly the 68060 library.
If you want to run COP prior to these tools, specify the SET60 option.
This flag DOES NOT change the processor flags in the exec.library!
NOMMU Disable the MMU bypass. COP won't touch the MMU and
keep it active all the time - as needed for amiga models that use the
MMU to load an OS image or to guarantee reliable DMA operations, as the
040 and 060 based Amigas. Disabling the MMU in this case will crash the
system because the OS will vanish. This keyword is identical to the ENVI.U
instruction.
MMU The default. COP bypasses the MMU for memory access,
all addresses will be physical addresses. This is somewhat dangerous if the
MMU is required for system operation, as for '060 and '040 systems or if
the MMU is used to map in a different version of the OS.
NOEMU Instruct COP to bypass the 060/040 emulator traps to
the 68060.library or 68040.library - which must be installed and running
at the time COP is launched. These exceptions are generated if the
68060 detects an instruction that is not supported by the CPU directly
but has to be emulated in software.
It is, however, not quite clear if this option makes any difference at all,
or if it works - simply because I don't own a '060 for testing.
EMU The opposide and default setting. COP captures all
emulator traps as software failures.
The next three options contol the video mode used by COP for its own display:
NTSC Use a NTSC screen for the debugger screen. This has
been the default for versions up to 1.56.
PAL Use a PAL screen instead. This is, however, more
flickering but required for some TVs.
PAL60 This is a display mode half between PAL and NTSC.
It uses the base frequency of NTSC, 60Hz, but does
no long/short line toggling, like PAL. This mode
might be required to display 60 Hz with some oldish
flicker fixers.
PICASSO Tell COP that the "Picasso96" graphics system and
a graphics card is installed. COP will then try to
saveback the status of the RTG system and to bring
the native amiga display to front. This option
requires the "picasso96" installed, most important
the "rtg.library".
I don't know how well this works, though, it's
currently a bit "hackish".
NOPICASSO Disable the use of the Picasso96 graphics software.
DARKEN Darken the native Amiga display upon initialization
of COP. This is useful for graphics board software
that leaves the native Amiga screen white.
This option is currently a bit "hackish".
Now some options that tell COP where to place itself in memory. They do
not work if COP is already loaded !
CODE where Tell COP where to place its CODE segment. where
might be:
FORWARD Allocate memory from the beginning of the memory
area, so COP is placed at LOW addresses.
This is impractical in most cases.
REVERSE Allocate memory from the end of the memory, so
COP is placed at HIGH addresses. This was the
default up to release 1.18.
address Place COP at an absolute address, given in decimal
or in hex if preceded by $ or 0x.
This memory area must be available, as long as you
do not use the FORCE option.
DATA where Tell COP where to place the DATA section. The
argument is the same as above.
BSS where ...same for BSS section
CHIP where ...same for CHIP section. If you use an absolute
address here, make shure it is in chip mem !
LABEL where ...same for LABEL section, which is needed if
you give a DDT (see below) and containes
the names and addresses of DDT labels.
BUFFER where Tell COP to use a chip-memory backup buffer and
place it according to the argument. You MUST
provide this argument if you want a chipmem backup
area, or the ENVI.B command won't work.
RESIDENTSTRUCT where Tell COP where to place the resident structure that
is needed for COP to keep resident over resets.
This argument is only useful if you use the
RESIDENT switch too.
FORCE Tell COP to use the specified memory, even if it is
occupied by another program. WARNING !
YOU SHOULD BE REALLY SURE WHAT YOU ARE DOING if
you MUST use this option ! Portions of code of
other programs might get overwritten by COP, causing
a fantastic crash !
FLUSH Flush labels loaded as symbols from a segment,
e.g. loaded by CLIDEBUG or WBDEBUG.
This is done automatically every time if you
specify CLIDEBUG or WBDEBUG.
However, the labels defined in the DDT file
are left alone.
FLUSHALL Flush all labels, even those defined in a
DDT file. The system labels AbsExecBase, Version
COPVBR and COPVVBR survive.
CLIDEBUG Debug a program using the Shell interface. If
you want to give arguments to the program to
debug, INCLUDE THE COMMAND AND ITS ARGUMENTS
in double qoutes. Since a colon and an asterisk
is interpreted by COP as the beginning of a
comment, you MUST enclose these characters
in an additional pair of single quotes.
To simplify this, you might use the DEBUG
script.
CLIDEBUG always flushes the labels.
WBDEBUG Debug a program thru the workbench interface.
If you want to support a second icon which is
simulated to be clicked with the main program's
enclose THE MAIN AND THE SECOND ARGUMENT IN
DOUBLE QUOTES. DO NOT ADD ANY .INFO TO THE
NAME, even if you load an icon of project type.
The responsible program will be found and be
loaded.
WBDEBUG always flushes the labels.
SYMBOL Add the symbols of the given binary file to
the label buffer. To do so, you MUST support
the base address of the segment using
SEGMENT or FIRSTHUNK.
Adding of additional labels might be necessary
if you debug an overlayed program. COP cannot
load all labels on startup, since it is not clear
where the overlay nodes will be placed in memory.
Remember the base address of the program if loaded;
Later on, if the overlay nodes are present, reload
the symbol table by FLUSH SYMBOL <progname>
FIRSTHUNK addr.
FIRSTHUNK Give the APTR to the first byte of the first hunk
to which the labels to be loaded belong.
Either FIRSTHUNK or SEGMENT MUST BE USED as an
additional argument if you use SYMBOL.
SEGMENT Give the BPTR, as available from LoadSeg(),
of the segment to which the labels to be loaded
by SYMBOL belong.
Either this or FIRSTHUNK IS REQUIRED for SYMBOL.
CALC Calculate the expression given. Everything COP's
EVAL command can evaluate is valid here, even
defined labels. So to read the value of ExecBase
using the Shell is quite easy:
COP CALC [AbsExecBase]
Note that this allows using COP as a symbol data-
base, e.g. to remember the system entry points.
COP CALC OpenLibrary
will give the offset of the OpenLibrary system
call, provided you added it using a DDT.
The only caveat is that COP will assume all
numbers are in DECIMAL unless preceeded by $.
(Different to how expressions are handled usually!)
The $ notation, however, may conflict with
shell variables, so enclose the argument, also
if it contains spaces, in double quotes.
If you want to build an icon to start COP from the workbench, use for
example the following tooltypes:
DISPLAY MUST be present to prevent COP from remote-
debugging mode.
GO MUST be present if you want to start COP.
DDT file Setup COP's labels using a data description
table. The syntax of this file is descripted
below, and a default table "startup.ddt" is
included in this drawer. If you want to run COP
together with the macintosh emulator, you should
specify the macintosh-version of the ddt file
called MAC.ddt and the MACMODE command line
switch.
You should use this option in your startup-
sequence to load all default labels.
It is fine to call COP again with this option
if you want to add some labels, however, if you want
to reload the table, you should flush all the
old labels with the FLUSHALL option.
PRE file Provide or create a precompiled version of a DDT
file. If this argument is given, COP tries first to
read the label database from the "pre" file. If
this file is not available, COP will read the usual
DDT file and create a "PRE" file for you. The ad-
vantage of precompiling "DDT" files is that they
are parsed much faster. Their format is, however,
private.
Of course, if COP is already present, the code loaded will get started and
will not be loaded again (and therefore, some options are useless in this
case !)
If you want to debug a Shell program, this command line would be nice:
COP CLIDEBUG "c:copy s:Startup-Sequence to '*'"
will debug the copy command in copying the startup-sequence to the console.
Please note the necessary quotes around the command line and the star.
To debug a Workbench progam, say the Shell-Icon, type:
COP WBDEBUG "SYS:Shell"
Debugging overlayed programs is a bit tricky. First load the program
itself, e.g. with
COP CLIDEBUG "SetVNC"
Now write down the address of the breakpoint when COP is entered.
Step thru the code until a new overlay segment is loaded. To do so,
set a breakpoint in the overlay manager, which will always be the first
hunk of the program. Then, load the symbols of the overlay code using
COP FLUSH SYMBOL "SetVNC" FIRSTHUNK 0x<addr>
where addr is the address of the breakpoint you wrote down before.
One caveat using overlays is that the structure of the overlay table
depends on the overlay manager the program uses. There are quite a lot
of them, however, COP only knows the default one supplied with the
linker BLink or SLink. As an example, the overlay structure of
DPaint II or COP (yes, that's me...) is private and is not supported
by COP. In this case, you cannot load symbols which are placed in the
overlay nodes, sorry.
If you want to use COP with the shapeshifter macintosh emulator, I suggest
the following command line:
COP FASTVBR NOMMU MACMODE DDT S:Mac.ddt
plus your prefered keymap and display settings. COP can be entered from
the macintosh finder interface thru the hot key, as usual. Once entered,
the hardware traps are captured by COP, not by the MacOs. However, the
system failures (except those generated by hardware traps) are still left
to the Os. This might change in a future release.
XII) Syntax of a data description table
-----------------------------------------------------------------------------
The data description table contains information about labels, that are
litaral names given to addresses to make code more readable. COP intro-
duces a new concept of label creation not available with any other de-
bugger.
The labels are sorted by "type", as there are:
- absolute labels, refering to one static address in memory.
This is the only type of label most debuggers support.
- equates. Those are simply names for numerical constants and
are never used in actual disassembling. You may use it, how-
ever, in expressions (and, in a release to come, in the
microassembler)
Typical equates are offsets of fields in structures.
- node relative labels. If COP finds a specific base pointer
points to a named exec-node structure (e.g. a library), this
type of label is used to generate a name for the offset from
the base of the node to the piece of memory which is addressed.
A typical case is a entry point in a library, but also the full
structure of a library can be addressed like that. So the default
ddt includes the whole structure of execbase and gfxbase.
Since the linking is done in the run time, it is not necessary
to open these nodes, and the nodes even does not need to exist in
memory while creating the labels.
- address relative. This type is currently not used, but is
useful if a base register is setup to point to the data region
of a program. Typically, this will be a5 or a4.
- a guru equate. This special type is used for giving readable
names to guru meditations and is never used by the disassembler,
but by the REGS.G instruction - And therefore every time COP is
entered by a crash.
- bit definitons. Useful for giving readable names to bits, but
not used by the disassembler (there are way to many of them).
- New with version 1.52 of COP, lineA-emulators can be named, too.
These traps are never used by the AmigaOs, but function as Os-
calls for a macintosh or Atari-ST emulator.
The syntax of a ddt file is a strange mixture of the syntax of the CBM
.fd-files and assembler include files, so you can use your .FD-files
and include files WITHOUT ANY CHANGE, provided you use the CBM macros
defined in exec/types.i and provided that you do not use forward
references, as they are not supported.
Entries in the DDT are
i) COPDDT-commands, a superset of the commands in the .fd files.
COPDDT-commands are preceeded by two hashmarks and MUST be placed
in the very first column.
ii) Pure labels and function entries are given by their names and must
placed in the first column of the file, like labels in assembly
language. As a special case, a label might be followed by a
EQU or SET opcode. The first produces an equate label with
a given value, and the second is ignored by COP since it is
only used to keep track of the included files.
If no value is given for a label, the contents is taken from
the offset-counter which can be set by ##offset or ##bias.
The type of the labels can be set by a COPDDT command pre-
ceeding the label, except for labels defined by EQU, which
are always equates.
A pure label without EQU will always increment the ##offset
counter by a size which can be set by ##increment.
iii) Pseudoassembler commands which are named like the default CBM-
macros in the exec/types.i file. They mostly define a label of
a type defined by some COPDDT command above, and the value
is also taken from the ##offset counter. However, the
increment depends on the pseudoassembler command.
iv) Comments are introduced by a colon or an asterisk like in
assembly language.
Here the COPDDT-commands:
##node name Setup the next labels as labels relative to the
node with the given name. Should be used for
library offsets.
##vectors name Identical to ##node, except that it defines function
vectors. The label values should be negative.
##guru Setup the next labels as numbers of guru-meditations
##absolute Setup the next labels as absolute addresses.
Never used with the Amiga-Os, since there is only
one fixed address (AbsExecBase), which is already
defined as a label. However, this type is used for
the low-memory variables of the macintosh Os
(what a horror !)
##relative <expr> Setup the next labels as offsets to the address
given by <expr>, which need not to be a number,
and may contain other evaluable labels. However,
forward references are not supported.
##equate Setup the next labels as pure equates.
##linea Setup the next labels as line-a traps, as used by
the MacOs and Atari ST. Useless for the Amiga.
##offset <expr> Set the offset of the next labels relative to their
base. With amiga only useful for labels of ##node,
##relative or ##equate type, since there is only
one fixed absolute address in the amiga and no
line-A emulators. Useful for ##absolute and ##linea
under MacOs and Atari ST.
##bias <expr> Set the negative offset of the next labels. Will
be used by .fd files to set library entries and is
identical to ##offset except that the value of
<expr> is negated (sign-changed).
##increment <expr> Sets the default incrementation value of the offset
counter. Should be set to -6 prior to including
.fd files, since each entry takes up 6 bytes, and
libraries grow to lower addresses. If you want to
define a table of LONGs, set the increment to 4.
This value is added to the ##offset counter every
time a pure label without a size gets defined.
Function entries in a .fd file are "pure labels"
in the sense of COPDDT.
##base name Define the name of a library base. Used by the
.fd files. Will define a label of offset
zero.
##include name Include another file in the ddt. There is NO
check for cyclic dependence, so WATCH OUT !
If the name contains spaces, include it in double
quotes.
##end End an ddt file. Also used by .fd files.
##private Quietly ignored by COP, only used in fd-files
##public Also ignored.
Empty lines or lines starting with a colon or a star are read as comment-
lines and are ignored, too.
Label definitions:
A "pure" label is defined by giving only its name starting in the
first row of a line, like this:
##absolute 8 ; Labels are of absolute type
##increment 1 ; Set the increment of pure labels
mylabel ; comments are welcome ! This label gets the value 8
nextlabel ; and this one 9, since the increment is 1
The value of the label to be defined is contained in the offset counter,
and it will be incremented by the value in ##increment every time.
Since fd-files contain functions and arguments, a (pure) label name is
cut in the first occurance of a left bracket:
myFunc(foo)(a0) ;this label gets called "myFunc" and got the value 10
Labels can be set to given values using the EQU pseudoassembler directive.
These "unpure" labels neither need the offset counter nor increment it.
All labels generated by this syntax are of equate type, regardless of the
previous COPDDT command.
TRUE EQU 1 ; an equate. Can be evaluated, but is
; not used by the disassembler
; the offset counter is untouched, too
The set directive of assembly language is known, but will be ignored without
any checking:
ARGC SET § ;in assembly language syntactically wrong,
;but completely ignored by COP.
The same goes for lines between a MACRO and a ENDM directive, since
COP does not support macros (and I think never will..).
Pseudoassembler commands:
They are called "pseudoassembler commands" cause they define labels in
assembly style, rather than .fd style. All macros in exec/types.i are
"emulated". The type of labels generated by them depend on the pre-
ceding COPDDT command, like ##absolute will generate absolute labels.
The value of the labels is given, as above, by the offset counter. This
counter can be set with the ##offset COPDDT command or the STRUCTURE
directive, and will be incremented by a value determinated by the
directive, unlike pure labels, which cause the value of ##increment
to be added.
Pseudoassembler directives MUST NOT start at the beginning of a line, but
MUST be preceded by spaces or TAB characters, like in assembly language.
Known directives are:
STRUCTURE name,<expr>
Define a new label of given name as the base of a structure. The offset
counter will be initialized by <expr>, that is, the structure containes
unnamed field in the beginning of the size given by offset. The value
of the label defined will be zero relatively to a base, which can be
setup by ##node or ##relative. Defining an absolute structure does not
make much sense in this system.
STRUCT name,<expr>
Define a substructure in a structure, that is, generate a label of given
name with the value as the value of the offset counter, and of type
given by a preceding COPDDT command. The offset counter is incremented by
the value of <expr> afterwards.
LABEL name
Define a label with the value of the offset counter, which is not
incremented at all.
UBYTE name[,<expr>]
Define one single byte, or array of bytes by generating a label. Its
value is given by the offset counter, and its type is given by a preceding
COPDDT command. The offsetcounter is incremented by 1, if the expression
is ommited, or 1x<expr> to generate an array.
BYTE name[,<expr>]
Same as byte.
UWORD name[,<expr>]
Define one single word, or array of words. Works like BYTE, but the offset
counter is incremented by 2 or 2x<expr>. If the offset counter is odd, it
is rounded to the next even number.
WORD name[,<expr>]
Same.
BOOL name[,<expr>]
Same.
ULONG name[,<expr>]
Defines one long word, or array of longwords. Increments by 4 or 4x<expr>
and alignes offset counter.
LONG name[,<expr>]
Same.
APTR name[,<expr>]
Same.
CPTR name[,<expr>]
Same.
FPTR name[,<expr>]
Same.
FLOAT name[,<expr>]
Same.
DOUBLE name[,<expr>]
Defines a IEEE-double precision entry or array. Increments the offset counter
by 8 or 8x<expr> and alignes it.
UQUAT name[,<expr>]
Same.
QUAT name[,<expr>]
Same.
EXTENDED name[,<expr>]
Introduced in COP, defines MC68881 extended precision entry or array.
Increments the offset by 12 or 12x<expr> and aligns it.
ALIGNWORD
Explicitly aligns the offset counter to the next word.
ALIGNLONG
Align the offset counter to the next long word.
ENUM [<expr>]
Initializes the ENUM-counter by the given value. Does not generate any label.
ENUMITEM name
Generate a label of equate type. The value is given by the equate counter,
which will be incremented by one after the definition.
BITDEF pre,post,<expr>
Generate two (!) labels. The first is of bit-type and will be named
"preB_post" and will have the value given by <expr>. The second will be
named "preF_post", is of equate type and has the value of 1 << <expr>.
IFD,IFND,ENDC
Ignored by COP
INCLUDE
Ignored by COP. To include something, use the COPDDT command ##include.
This was mainly done to avoid unnecessary includes and to give the
control what will be included to the main DDT-file.
LIBINIT
LIBDEF
Also ignored by COP
MACRO
...
ENDM
Lines between MACRO and ENDM are ignored by COP, since it does not support
macros.
As noted above, the set of supported commands was choosen in a way such
that all orignal CBM-includes and .fd files can be used without a change.
Support of other style assembly include files (like DevPac's rs-counter)
are not supported and never will.
It is, however, sometimes necessary to explicitly define labels on one's
own. This happens mostly if the orginal include file defines useful
constants that should be relative to a base as equates. An example is
the definition of DOSBase in dos/dosextens.i. Since you cannot make
all labels relative to DOSBase, one must take this definition out
of the file.
Defining DOSBase as equates and not as node relative is of course not
illegal in COP, but will be of no use for the disassembler since it
ignores equates (there are too many of them to be of any use). This was,
as a second example, necessary in defining the hardware offsets.
Originally given as equates, they are now relative to the base of
the custom chip set. See the included example ddt file.
XIII) Precompiled files
-----------------------------------------------------------------------------
The 1.60 version of COP introduces the option to "precompile" DDT files for
faster startup. If you give a name of a pre-file on the command line with
"PRE filename", additional to the "DDT" keyword, COP will try first to load
all labels from this pre-compiled header. If successfully, the DDT keyword
will be ignored. If the "PRE" file is not available, COP will parse the "DDT"
file as usual and will create this "PRE" file afterwards so it is available
for later use.
The main advantage of precompiled "DDT" files is that they are way faster to
load, no parsing and no syntax check is required. The data format is
completely internal, please do not touch these files - they are purely for
COPs use and maintained completely by COP itself.
One caveat of "PRE" files is that they aren't updated automatically if you
change the original "DDT" file and there can be ONE and ONLY one "PRE" file
for the complete set of macros. Writing a partial set of label definitions
in a pre-file isn't possible. Either all or nothing!
The consequence is that you:
- should delete the "PRE" file manually if you made changes to the source DDT
file. COP will then re-create the "PRE" file the next time it is required.
- should only precompile the first DDT file that is loaded, that is the
"startup.ddt" file. Since this is the only DDT file in most applications,
that's not a restriction. DO NOT TRY to write PRE files for DDT files you
include afterwards - as they will not only contain the label definition in
the additional DDT file but in ALL DDT files. Loading these labels later on
might confuse COP.
As a rule of thumb: Only the Startup.DDT file should be precompiled.
XIV) Shell scripts
-----------------------------------------------------------------------------
Three shell scripts are provided with COP, to simplify work:
-Debug Accepts a program name (full path required) and its
arguments to be debugged by COP. Will load the program
as if started from the Shell and set a breakpoint at the
first hunk.
-WBDebug Accept a workbench program and, optionally, a secondary
selection, without .info. Starts the program and supplies
the arguments thru a WBStartup message, as if started from
the workbench.
-Calc Evaluates the supplied argument. Labels are welcome, and
the radix defaults to decimal. However, problems may
arise if you use hex numbers cause the $ can cause
conflicts with defined shell variables. In this case,
enclose the argument in double quotes.
XV) COP and MuForce/Enforcer/Cyberguard
-----------------------------------------------------------------------------
COP 1.56 supports the Enforcer program if run on a MC68020 or MC68030, it
supports MuForce on any processor. It *might* support the Cyberguard, too,
but the 040 exception handler of this program is faulty and I won't recommend
this program for that reason.
There are two ways to run these tools together with COP, depending on which
output you need.
Method I): Start MuForce first, then run COP.
Don't remove it later. This is the recommended way.
This will redirect Enforcer hints directly to COP. Faulty programs will cause
a bus error exception, and you're now able to debug these programs directly.
The enforcer won't cause any ouput, running "Sushi" is not necessary.
If you made COP resident, the COP invokation line in the startup-sequence
should contain the "RESTOREVBR" keyword, too. This is needed because the
order of installation will be different once COP is resident - MuForce
will now install on top of the resident copy of COP, hence, messing COP's
vector base register. This option will re-direct the vector base to COPs
interal base.
Method II): Start COP first, then load MuForce. It is possible to
remove MuForce later on, however.
The MuForce will work as usual with this setting, COP won't interfere in this
case.
However, as soon as COP is entered, it will complain about its vector base
being messed up by MuForce. You might want to simply ignore this warning.
MuForce and the FASTVBR option.
--------------------------------
That's a story of its own. If you want to run COP before MuForce, the
FASTVBR option IS REQUIRED. This is simply due to the fact that otherwise
COP will locate the virtual vector base in the first 1K/4K of memory as
usual - and this memory isn't available with MuForce.
Quite the same goes for keeping COP resident - it's in this case already
present when MuForce gets loaded, so FASTVBR is mandatory, too.
There's actually little reason NOT to use the FastVBR option except to keep
some badly written programs - mostly games - working.
XVI) COP and the 68060 / 68040
-----------------------------------------------------------------------------
The 1.61 release of COP should be able to support the 68060 processor -
however, as most of the support code is untested, it is not quite clear if
everything works as expected.
The following rules apply to COP and the 68060:
-----------------------------------------------
- Add the SET60 keyword to the command line option. That tells COP explicitly
that it has to deal with the '060 processor. The execbase "AttFlags" flags
field does not necessarely monitor the '060 processor correctly.
- Add the NOMMU keyword. The MMU operation is vital for '060 and '040 based
systems, to mask certain regions of memory as "non-cacheable" as needed for
DMA transfer and other reasons.
- Add the NOEMU keyword. COP will try to bypass the emulator traps to the
68060 library. It is, however, not quite clear if this works as expected.
- Load the 68060 library BEFORE COP is run. This is usually done by the
68060.library that gets loaded by SetPatch.
- Start COP after CyberGuard or Enforcer. This is the recommended way, but
it is not yet quite clear if this works like it should. COP has to emu-
late the access to the AbsExecBase location at address four, and this
emulator code is quite tricky for the 68060. Even though I tried my best
to test it with my 68030, it is not clear whether it works like it should.
- Add the FASTVBR option if you want to run COP before Enforcer/CyberGuard,
or if you want to keep COP resident. Do not specify it otherwise.
COP and the 68040
-----------------
- Add the NOMMU keyword. It is required for proper DMA operation of '040
systems.
- Add the NOEMU keyword. COP will try to bypass the emulator traps to the
68040.library.
- Run COP after MuForce. Don't use the Enforcer because its design is too
static to allow proper operation. Don't use CyberGuard because its
exception handler is not working properly.
- Run COP after loading the 68040.library. This is usually done by the
SetPatch command anyways.
- Specify the FASTVBR keyword if you run COP before Enforcer, or if you
want to keep it resident. Do not specify it otherwise.
XVII) Plans
-----------------------------------------------------------------------------
- Making the chip-buffer more transparent
- Better memory chunk support
- better disassembler, parts are already working
- a microassembler (in preparation)
- wildcards in node matching
- bitdefs should really be relative to something, but system includes
do not give the information
- more macintosh support, thru a mac INIT.
- a MMU table lister ?
In the next time, there won't be...
- a floppy or harddisk support. There are so many filing systems and device
drivers and I think using the 20K or more needed to implement this stuff
can be used a better way.
XVIII) Final remarks
-----------------------------------------------------------------------------
COP should not be crunched or compacted since COP uses an internal overlay
format to load the debugger code if needed. To enter COP later with a
COP DISPLAY GO or equiv. the startup segment is loaded to memory only.
I wrote COP six years ago (1993) to find the reason of many crashes that
occured in my system. I found that most debuggers I knew were not
able to debug a system with execbase out of order or input.device crashed.
The first debugger I used to accomplish this task was the ROMWack, a very
simple, but nevertheless useful one.
It took a year to complete the first release of COP, so I can appreciate a
programmer's work and you should do so, too. Please use COP to find bugs
in your own code only, whenever every other debugger fails, e.g.
interrupt code or reset resident code. Use COP to find the reason of
system crashes that crash normal debuggers, but PLEASE DO NOT USE COP TO
FUMBLE IN FOREIGN CODE, since this will prevent people from writing
good programs. Not everthing is public domain today, support the good work
and buy software.
This program is decidated to all the bubbling idiots that debug own code
up to 4 a.m. in the morning ("It MUST work...").
P.S.: The reason for the crashes, if anybody cares, is the broken expansion
port in my A2000. Replacement motherboards are no longer accepted, because
I got a replacement now... (-;
Thank goes to:
-Oliver Spaniol for letting me debug this proggy on his '060.
-Mark Watson for his help with the '060 code.
-Werner Müller for providing a 040 and a (working) 6.2 motherboard for
a bargain.
If you like this program, if you have any suggestions, if you want to get a
newer release of COP, write to:
Thomas Richter
Rühmkorffstraße 10 A
D-12209 Berlin
Germany
-------
or send electronic mail to
thor@math.tu-berlin.de
There's also a web site you should try:
WWW: http://www.math.tu-berlin.de/~thor/thor/index.html
It might be possible that COP does not work on YOUR Amiga, some parts of
the code are very tricky and hardware dependent. I tried to avoid such
problems, but one can never know. If COP fails on your computer, send
me a mail and descripe as best as possible your problems. However, debugging
by mail is a complicate task....
Thank you for reading and have a good time...
THOR (June 1999)